Back to Main Menu

MapInfo Pro Integration Configuration

Introduction

The assetic_mapinfo python package provides a set of tools that can be used in the MapInfo Pro desktop environment to create/update assets in Assetic and to update the corresponding feature in MapInfo Pro with the Assetic asset ID.  The feature spatial definition in MapInfo Pro can also be copied to Assetic so that the the Assetic map and Assetic spatial search tools can be used with the asset.

Configuration of assetic_mapinfo tools

Two configuration files are required.  The default implementation of the integration expects these files to be located in a folder named 'Assetic' within the users roaming profile folder.  The roaming profile folder location is defined by the Windows system environment variable APPDATA.  The simplest way to navigate to this folder is to type %APPDATA% in Windows Explorer and hit enter:

The configuration files to create in the folder %APPDATA%\Assetic are:

1. An Assetic REST API authentication file.  This is used to define your connection details for your Assetic environment.  Refer to the article Assetic-Python-SDK-Quick-Start for the structure and content of this file.
2. An XML translation configuration file for:

• logfile – the name of the log file to write messages and exceptions to.
• loglevel – the Python log level name, e.g. ‘debug’ or ‘info’. Debug will show a far greater level of detail and is used when first testing the implementation, and in problem solving.
• Asset Category to MapInfo Pro layer field mapping.
  • Define the Assetic asset category that the layer corresponds to.
  • Define the field in MapInfo Pro that corresponds with the Assetic unique id.
  • Define the initial status of the created asset.
  • Define whether to upload the spatial feature to Assetic.
  • Define components to be created against the asset.
    • Define dimensions to be created against the components.
  • Define fields in the layer that correspond to fields in Assetic.
  • Define hardcoded default values to use instead of field map layer field values.
  • Optionally define Functional Location to associate asset with
  • Define the record count threshold above which the integration uses Data Exchange to apply asset updates rather than per asset updates.  The default is 250 records.
• Functional Location to GIS layer field mapping

Sample XML Configuration File

The XML sample file mapinfo_edit_config.xml includes comments that explain the configuration structure and usage.

Download Sample Note: You may need to right click and 'Save As' to download

XML Configuration File Structure

The following section details the configuration file structure using the sample configuration file mentioned above.

General Configuration Settings

The following settings allow the location of the log file and the log level to be set.

Python log levels are listed in the python help: logging

<logfile>c:\temp\logfile.log</logfile>
<loglevel>info</loglevel> 

Layer Settings

Configuration is per MapInfo Pro layer, as defined by the layer name in the sample below. In this instance the layer name is 'UnsealedRoads'.   Within the configuration file multiple 'layer' nodes may be defined, with the 'name' differentiating each node.

<layer name="UnsealedRoads">

Within this layer node is settings specific to the layer.

The following nodes can be defined:

• category.
  • This is mandatory.  Defines the Assetic Asset Category to associate with the layer.  Use the name of the category as shown in the Assetic application UI.
• creation_status
  • When creating an asset for this layer, indicate what the status should
    be for the new asset. If omitted the default is 'Active'. Can be one of:
    • Active
    • Proposed
    • Notional Asset
• upload_feature
  • Boolean flag indicating whether to maintain a copy of the spatial feature in Assetic.  If 'True' the spatial feature will be created in Assetic on asset creation, and updated when the feature is updated.

<category>Roads</category>
<creation_status>Active</creation_status>
<upload_feature>True</upload_feature>

Asset Configuration

The following settings apply to asset creation/update.

Core Fields

The node 'corefields' is used to define the field translation between the MapInfo Pro layer and the Assetic asset 'core' fields as listed in the article Asset Integration Overview.

In the XML example below the field translations are:

<corefields>
 <!--Name of the layer field name used to record the assetic asset identifier-->
 <asset_id>assetid</asset_id>

 <asset_name>assetname</asset_name>
 <asset_class>class</asset_class>
 <asset_sub_class>subclass</asset_sub_class>
 <asset_type>type</asset_type>
 <asset_sub_type>subtype</asset_sub_type>
 <asset_external_identifier>externalid</asset_external_identifier>
 <asset_security_group>securitygroup</asset_security_group>
 <asset_criticality>criticality</asset_criticality>
</corefields>

Asset Id Configuration

Within the Assetic application there are 2 options for how the Asset Id is generated. These 2 options apply per Asset Category, and can therefore differ between Asset Categories.  The article Asset Auto ID Generation further outlines these 2 options.

• Asset Id Auto-generation:
  • Within the Assetic application a system administrator sets the Asset Category to have the asset Id auto-generated.  When the asset is created no asset Id needs to be supplied.  On creation of the asset Assetic generates a unique asset id which is returned to the user, and displayed against the asset.
  • In this scenario if you define a field in MapInfo Pro that translates to Assetic asset Id the integration will populate the MapInfo Pro field with the Assetic asset Id upon asset creation by the integration.  It is not mandatory to provide a field translation for asset Id.
• User Defined Asset Id:
  • If you wish to generate the Asset Id externally to Assetic, and provide the asset Id upon asset creation then asset_id becomes a mandatory 'corefield' in the configuration.  This field will need to be populated within MapInfo Pro with a unique asset Id.

The 'asset Id' is a user visible unique identifier for the asset.  The Assetic REST API's utilise a hidden Id that uniquely identifies the asset.  This hidden Id is a system generated GUID and is always returned by the Assetic REST API whenever an asset is created.  This Id can optionally be recorded against the feature in MapInfo Pro.  If using a user defined asset Id the integration can optionally update the MapInfo Pro feature with the Id upon asset creation.  This assists with establishing which features in MapInfo Pro have a corresponding asset in Assetic.

In the following XML configuration example the MapInfo Pro field 'assetguid' will be updated with the Assetic Id upon asset creation.

<corefields>
 <id>assetguid</id>
</corefields>

Core Defaults

The node 'coredefaults' allows hard coded values to be applied to core asset fields upon asset creation/update.

In the example below the assets associated with the ESRI layer will all have a default Work Group of 'Transport'. Multiple work groups have also been specified to assign the asset, separated by a comma (,).

<coredefaults>
 <asset_work_group>Transport</asset_work_group>
 <work_groups>Transport,Fleet,Services</work_groups>
</coredefaults>

Work Groups Configuration

If specifying an Assetic work group mapping for a layer, the XML configuration for the integration allows for defining either a single 1-to-1 linkage of a work group for an asset, or alternatively also provides the option for the integration to link an asset to a list of multiple work group values to utilise the Assetic multiple work group functionality for assets. This is achieved by parsing a collection of work group values, which have been delimited by a particular character, in order to create/update an asset and assign it to more than 1 work group.

For work group configurations in the XML file, the core field elements "asset_work_group" and "work_groups" are used, which are outlined below:

• asset_work_group
  • the asset's default work group
• work_groups
  • a delimited list of one or more work groups

Single Workgroup

For situations where an asset will have a 1-to-1 to just a single work group, and the workgroup is thereby also the default, only the XML element "asset_work_group" needs to be mapped and populated within the XML configuration. The "work_groups" XML element does not need to be provided. In this scenario, a single work group value that has been specified as the default will be applied as both the default and also as a single workgroup value for the asset's work groups list during creation or updates.

Multiple Workgroups

For mapping and specifying an asset to be assigned more than 1 work group, both of the 'asset_work_group' and 'work_groups' XML elements must be included in a layer's configuration to utilize the multiple work group functionality. The value specified as the asset's default work group should also be included as part of the overall delimited list of multiple work group values.

Depending on the desired character to be used for the separation of work group values, the "multiple_work_group_separator" setting at the layer level can be utilized. By default, the separator character is set to comma (,) if it this element has not been specified within the XML. If included in the XML layer settings, a custom separation character can be specified as required if the default value of comma is not suitable.

Asset Name Configuration

The Asset Name is mandatory, however it does not need to be unique.  The asset name can therefore be defined in either 'corefields' as a field translation to an MapInfo Pro field, or defined in 'coredefaults' with a default name.

Attribute Fields Configuration

Assetic 'non-core' attribute field translations are defined in the XML node 'attributefields'. The name of each child node is the Assetic asset attribute name with the value being the MapInfo Pro field name. The attribute field names, unlike the core field names, are represented as the case sensitive names in Assetic. e.g Zone remains as Zone.

The XML child node name is the Assetic internal attribute field name (not the field label).
Refer to the 'Asset Attribute Fields' section of the Asset Integration Overview article to understand how to obtain the Assetic asset attribute field names.

In the example below the MapInfo Pro field 'ZONING' translates to the Assetic asset field 'Zone'.

<attributefields> 
 <Zone>ZONING</Zone>
</attributefields>

Attribute Defaults Configuration

The XML node 'attributedefaults' allows hard coded values to be applied to 'non-core' asset attribute fields upon asset creation/update.

In the example below the assets associated with the MapInfo Pro layer will all have a Work Group of 'Transport'.

In the example below the same comment is applied to all assets in the MapInfo Pro layer.

<attributedefaults>
 <Comment>Look at me! I created a new asset.</Comment>
</attributedefaults>

Asset Component

The configuration file allows for one or more components to be created/updated for an asset.

The 'component' node is optional and may be omitted from the XML if components are not required.

Each 'component' node within the 'layer' represents a different component.

The component type makes each component unique, and therefore must not be repeated for another component configuration within the same layer configuration.

The list of component fields is provided in the 'Components' section of the article Asset Integration Overview.

Component Fields Configuration

The node 'componentfields' is used to configure MapInfo Pro fields that correspond to an Assetic component field.
The node name is the Assetic component field name (python format) and the node value
is the field name in the layer.

The following example defines the MapInfo Pro fields 'SURFACELIFE' and 'SURFACEMATERIAL' translation to Assetic component 'DesignLife' and 'MaterialType'.

<componentfields>
 <design_life>SURFACELIFE</design_life>
 <material_type>SURFACEMATERIAL</material_type>
</componentfields>

Component Defaults Configuration

The XML node 'componentdefaults' allows hard coded values to be applied to component fields.

This allows the ComponentType to be set which is important because it is the component type that differentiates this component from any other component created against the asset. 

The component 'Label' field is the component name displayed in Assetic.  

In the XML example below the field translations are:

<componentdefaults>
 <label>Surface</label>
 <component_type>Surface Main</component_type>
 <dimension_unit>Metre</dimension_unit>
 <network_measure_type>Length</network_measure_type>
 <financial_class_name>Roads</financial_class_name>
 <financial_sub_class_name>Sealed Roads</financial_sub_class_name>
</componentdefaults>

Asset Dimension Configuration

The configuration file allows for one or more dimensions to be created/updated for a component.

The 'dimension' node is optional and may be omitted from the XML if dimensions are not required.

Each 'dimension' node within the component represents a different dimension.

The combination of dimension record_type, network measure type, and shape name makes each dimension unique, and therefore must not be repeated for another dimension configuration within the same component configuration.  A dimension may be created without a shape, in which case 1 dimension record without a shape per network measure type and record type is supported, along with other dimension records that have unique shapes.

The list of dimension fields is provided in the 'Dimensions (Network Measure)' section of the article Asset Integration Overview.

Dimension Fields Configuration

The node 'dimensionfields' is used to configure MapInfo Pro fields that correspond to an Assetic dimension field.
The node name is the Assetic dimension field name (python format) and the node text value
is the field name in the layer.

In the example below the Assetic fields 'length' and 'width' are the node element names and the node text '_geometry_length_' and 'WIDTH' are the MapInfo Pro layer field names (_geometry_length_ is a special field).

<dimensionfields>
 <length>_geometry_length_</length>
 <width>WIDTH</width>
</dimensionfields>

Dimension Defaults Configuration

The XML node 'dimensiondefaults' allows hard coded values to be applied to dimension fields.

This allows the RecordType to be set which is important because it is this dimension record type that differentiates this dimension from any other dimension created against the component. 

In the XML example below the field translations are:

<dimensiondefaults>
 <unit>Square Metre</unit>
 <record_type>Info</record_type>
 <network_measure_type>Area</network_measure_type>
 <shape_name>Rectangle</shape_name>
 <length_unit>Metre</length_unit>
 <width_unit>Metre</width_unit>
</dimensiondefaults>

Address Configuration

The address of an asset is set via the address configuration.

If the address is not required then omit the following nodes from the configuration.
If defining address, 'country' is the minimum requirement.

Address Fields Configuration

The node 'addressfields' is used to configure MapInfo Pro fields that correspond to an Assetic address field.
The node name is the Assetic address field name (python format) and the node text value
is the field name in the layer.

In the XML example below the field translations are:

<addressfields>
 <street_number>HOUSE_NUMBER</street_number>
 <street_address>STREET_NAME</street_address>
 <city_suburb>SUBURB</city_suburb>
</addressfields>

Address Defaults Configuration

The XML node 'addressdefaults' allows hard coded values to be applied to dimension fields.
The node name is the Assetic address field name (python format) and the node text value
is the value to apply in Assetic

In the XML example below the field translations are:

Functional Location Association to Asset

The XML node 'functional_location' allows the asset to be associated with a functional location.

An asset may be associated with only 1 functional location.

The table below outlines the 3 GIS fields that may be used to define the association:

In the XML example below the field translations are:

 <functional_location>
   <functional_location_id>func_loc_fid</functional_location_id>
   <functional_location_name>func_loc_name</functional_location_name>
   <functional_location_type>func_loc_type</functional_location_type>
 </functional_location>

Functional Location

A new Functional Location may be created via a layer dedicated to Functional Location.

The XML configuration for Functional Location is at the same level as the Asset Configuration (it is not a child of the Asset Configuration).

All Functional Location configurations are defined in a node as shown below:

<operation action="Functional Location">

Within the "Functional Location" node each layer to Functional Location configuration is defined by specifying the layer name. In the example below the layer name is "local_govt_reserve":

<layer name="local_govt_reserve">

Like the Asset configuration, the Functional Location definition is broken into core fields and attribute fields, and supports fields from the GIS layer and hardcoded 'default' fields.

Core Fields

The node 'fl_corefields' is used to define the field translation between the GIS layer and the Assetic Functional Location 'core' fields as listed in the article Asset Integration Overview

The core fields are:

 <fl_corefields>
   <id>FL_ID</id>
   <functional_location_id>FL_FID</functional_location_id> 
   <functional_location_name>FL_NAME</functional_location_name>
 </fl_corefields>

Functional Location Id Configuration

Within the Assetic application there are 2 options for how the Functional Location Id is defined. These 2 options apply per Functional Location Type, and can therefore differ between Functional Location Type.  The article Functional Location Types further outlines these 2 options.

• Functional Location Id Auto-generation:
  • Within the Assetic application a system administrator sets the Functional Location Type to have the Functional Location Id auto-generated.  When the Functional Location is created no Functional Location Id needs to be supplied.  On creation of the Functional Location Assetic generates a unique Functional Location id which is returned to the user, and displayed against the Functional Location.
  • In this scenario if you define a field in the GIS layer that translates to Assetic Functional Location Id, the integration will populate the GIS field with the Assetic Functional Location Id upon Functional Location creation by the integration.  It is not mandatory to provide a field translation for Functional Location Id.
• User Defined Functional Location Id:
  • If you wish to generate the Functional Location Id externally to Assetic, and provide the Functional Location Id upon Functional Location creation then functional_location_id becomes a mandatory 'fl_corefields' in the configuration.  This field will need to be populated within the GIS with a unique Functional Location Id.

The 'Functional Location Id' is a user visible unique identifier for the Functional Location.  The Assetic REST API's utilise a hidden Id that uniquely identifies the Functional Location.  This hidden Id is a system generated GUID and is always returned by the Assetic REST API whenever an asset is created.  This Id can optionally be recorded against the feature in the GIS layer.  If using a user defined Functional Location Id the integration can optionally update the GIS feature with the Id upon asset creation.  This assists with establishing which features in the GIS have a corresponding Functional Location in Assetic.

In the following XML configuration example the GIS layer field 'fl_id' will be updated with the Assetic Id upon asset creation.

<fl_corefields>
 <id>FL_ID</id>
</fl_corefields>

Core Defaults

The node 'fl_coredefaults' allows hard coded values to be applied to core Functional Location fields upon Functional Location creation/update.

In the example below the Functional Location associated with the GIS layer will all be in the Functional Location Type 'Park Site'.

<fl_coredefaults>
 <functional_location_type>Park Site</functional_location_type>
</fl_coredefaults>

Functional Location Name Configuration

The Functional Location Name is mandatory, and although it does not need to be unique the integration requires that the name is unique for the given Functional Location Type. 

Functional Location Type Configuration

The Functional Location Type is mandatory and must be defined in either 'fl_corefields' as a field translation to a GIS layer field, or defined in 'fl_coredefaults' with a default name.  Typically it would only be defined as a field translation in 'fl_corefields' if the type differs between features within a layer.

Functional Location Attribute Fields Configuration

Assetic 'non-core' attribute field translations are defined in the XML node 'fl_attributefields'. The name of each child node is the Assetic Functional Location attribute name with the value being the GIS layer field name. The attribute field names, unlike the core field names, are represented as the case sensitive names in Assetic. e.g 'GroupAssetComment' remains as 'GroupAssetComment'.

The XML child node name is the Assetic internal attribute field name (not the field label).
Refer to the 'Functional Location Attribute Fields' section of the Asset Integration Overview article to understand how to obtain the Assetic Functional Location attribute field names.

In the example below the GIS layer field 'COMMENT' translates to the Assetic Functional Location field 'GroupAssetComment'

 <fl_attributefields>
   <GroupAssetComment>COMMENT</GroupAssetComment>
 </fl_attributefields>

Attribute Defaults Configuration

The XML node 'fl_attributedefaults' allows hard coded values to be applied to 'non-core' Functional Location attribute fields upon Functional Location creation/update.

In the example below the Functional Location associated with the GIS layer will all have a value for 'Zone' of 'Zone 2'.

In the example below the same comment is applied to all assets in the GIS layer.

 <fl_attributedefaults>
   <GroupAssetZone>Zone 2</GroupAssetZone>
 </fl_attributedefaults>